home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / bshow101.zip / BSHOW.DOC next >
Text File  |  1992-05-24  |  24KB  |  539 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                                   BShow 1.01
  15.  
  16.                                       by
  17.  
  18.                                   Ben Sandee
  19.  
  20.                                    05-24-92
  21.  
  22.  
  23.  
  24.                                Table of Contents
  25.                                =================
  26.  
  27.  
  28.         License, disclaimer, etc.................................... 1
  29.         BShow Features.............................................. 2
  30.         BShow Operation............................................. 3
  31.         Command line parameters..................................... 4
  32.         Configuration File Options - Global......................... 5
  33.         Configuration File Options - Unique to each Utility......... 7
  34.         Menu options in BShow....................................... 9
  35.         Adding Compression Utility Interfaces.......................10
  36.         Credits and copyrights......................................12
  37.  
  38.                                     1
  39.  
  40.  
  41.                   LICENSE, DISCLAIMER & MISCELLANEOUS INFO
  42.                   ========================================
  43.  
  44.     You are free to use BShow in any way you see fit, provided you follow
  45.     the following rules:
  46.  
  47.             A) Distribute copies of BShow with it's original archive contents
  48.                intact.  This means NO ADDITIONAL FILES!  You may repack the
  49.                archive with any archiver you wish, provided the original
  50.                contents are not disturbed.
  51.  
  52.             B) You may not SELL BShow.  (w/o previous written consent of
  53.                the author.)
  54.  
  55.             C) You may DISTRIBUTE BShow provided you obtain prior written
  56.                consent AND charge no more than $5 per copy.  If you plan
  57.                on charging more than $5 per copy, don't even waste my time
  58.                with a letter of permission.
  59.  
  60.     The author of BShow may not be held responsible for ANY damage BShow
  61.     may do to your system or data loss caused by its use.  BShow has
  62.     been extensively tested on a number of systems and SHOULD work on
  63.     yours.  However, the author cannot guarantee that it will work on
  64.     your particular setup.
  65.  
  66.     The Author may be contacted for questions or requests via the above
  67.     mail address, or on the JW-PC DataFlex.HST BBS at (608)837-1923 at
  68.     1200/2400/9600/12200/14400 HST/V.32bis, 24 hrs, Fidonet 1:121/8 or
  69.     RBBS-net 8:972/2.  The author may also be reached via echomail in the
  70.     RBBS-PC Conference on either RBBS-net or Fidonet.  The latest version
  71.     of BShow may also be FREQ'd via magic name BSHOW at either of the above
  72.     net addresses.
  73.  
  74.  
  75.                                     2
  76.  
  77.                               BShow Features
  78.                               ==============
  79.  
  80.     BShow is, quite simply, a new file viewer that is taking the country
  81.     by a storm with these features:
  82.  
  83.           - BShow will support virtually any compression utility!  A
  84.             simple change in the configuration file is all that is
  85.             necessary.
  86.  
  87.           - BShow is not limited to compressed files alone!  It will
  88.             view any file it is given, in one way or another.
  89.  
  90.           - BShow will display ASCII and binary files!  ASCII viewing is a
  91.             simple listing of the file, while binary mode offers a full
  92.             two-column hexadecimal dump.  With this feature, even
  93.             proprietary word processing formats may be read to some
  94.             degree!
  95.  
  96.           - String searches may be employed in either ASCII or
  97.             hexadecimal modes!  In hexadecimal mode, the ability to
  98.             search for either a hexadecimal string or a text string is
  99.             available.
  100.  
  101.           - BShow is shipped configured for ZIP, LZH and ARJ compressed
  102.             files.  But keep in mind, a new viewer is no longer
  103.             necessary whenever a new compression utility revision
  104.             becomes available!
  105.  
  106.           - BShow features easy BBS integration, and was in fact
  107.             designed to be used on a BBS system!
  108.  
  109.           - BShow supports baud rates of up to 38400 bps over COM1 and
  110.             COM2, but with the addition of a FOSSIL driver, support for
  111.             any system is easily attainable!
  112.  
  113.           - User definable work drives offer increased speed, with the
  114.             ability to use a RAM drive!
  115.                                     3
  116.  
  117.                                BShow Operation
  118.                                ===============
  119.  
  120.     BShow may be operated from either the DOS command line or a batch
  121.     file.  The examples in this document will assume BBS usage via a
  122.     batch file, but keep in mind that it can be operated from the DOS
  123.     command line with equal ease.  There is purposely an overlap between
  124.     the command line switches and the configuration file, so that the
  125.     user may decide what is desired to be flexible and passed on the
  126.     command line, and what is desired to be static and hardcoded in
  127.     the configuration file.
  128.  
  129.     In order to use BShow, the sysop will need the following files:
  130.  
  131.          BSHOW.EXE      The executable program. (Included)
  132.          SAMPLE.CFG     The configuration file. (Edit & Rename to BSHOW.CFG)
  133.          RBBSBATS.ZIP   Series of RBBS batch files to View compressed files
  134.          FORCE.ZIP      Series of FORCE batch files to View compressed files
  135.          PKZIP.EXE  -+
  136.          PKUNZIP.EXE |
  137.          LHA.EXE     +- Compression utilities as desired, user furnished.
  138.          ARJ.EXE     |
  139.          XYZ.ETC    -+
  140.          SPWN13.ZIP     Optional PD Desqview window spawning utility.
  141.                         (Included)
  142.  
  143.     Note SHROOM, or current version SHROM18G.ZIP, may give you all the
  144.     memory you need for ARJ, without DesqView, but it has not yet been
  145.     tested with BSHOW.  If you try it, let us know of the results. SHROOM
  146.     is a shareware product by Davis Augustine, of Cambridge, MA.
  147.  
  148.     Authentic BShow files will come packed in an -AV stamped ZIP file,
  149.     packaged by JW-PC Consulting.
  150.                                     4
  151.  
  152.                      Command Line Parameters for BShow
  153.                      =================================
  154.  
  155.     Conventions:      Required items labeled REQUIRED, defaults labeled
  156.                       DEFAULT; if parameter is skipped, default is taken.
  157.                       Square brackets surround user-supplied data, and
  158.                       should NOT be included in batch or cfg files!
  159.  
  160.     Filename.EXT    « REQUIRED.  BShow uses ext to determine compression
  161.                       format.
  162.  
  163.     /p[port]        « REQUIRED for remote operation.  If local BBS node
  164.                       passes 0 for port, baud is ignored and local
  165.                       operation is default.
  166.                       [0=LOCAL=DEFAULT]
  167.  
  168.     /wx:\workdir    « Uses work directory on drive x: (optional) and uses
  169.                       directory "WORKDIR", for processing.  You may specify
  170.                       a RAM drive for extra speed.  You will need enough
  171.                       space to hold the largest file within a compressed
  172.                       file, plus a couple kilobytes.
  173.                       [DEFAULT=CURRENT]
  174.  
  175.     /m[#]           « Maximum number of minutes in BShow.
  176.  
  177.                       Note:  The LESSER of either the command line OR the
  178.                              config file will be used by BShow.
  179.  
  180.                       [0=NO-LIMIT=DEFAULT]
  181.  
  182.     /t[#]           « maximum number of seconds of idle time.
  183.                       [0=NO-LIMIT=DEFAULT]
  184.  
  185.     /l[#]           « maximum number of lines total to be displayed per
  186.                       session.  (prevents user from doing massive ascii
  187.                       downloads)
  188.                       [0=NO-LIMIT=DEFAULT]
  189.  
  190.     /i[#]           « number of lines per page.
  191.                       [23=DEFAULT]
  192.  
  193.     /c              « turns CTS/RTS hardware flow control on.
  194.                       REQUIRED for locked baud operation.
  195.                       (w/o FOSSIL)
  196.                       [OFF=DEFAULT]
  197.  
  198.     /x              « turns XON/XOFF software flow control on.
  199.                       (w/o FOSSIL)
  200.                       [OFF=DEFAULT]
  201.  
  202.     /o[file.ext]    « points to configuration file.
  203.                       [BSHOW.CFG=DEFAULT]
  204.  
  205.     /f[ext]         « forces bshow to use config option for extension ext.
  206.  
  207.                                     5
  208.  
  209.  
  210.                          Configuration File Options
  211.                          ==========================
  212.  
  213.     See sample BSHOW.CFG in distribution package for specific examples and
  214.     suggested order of commands.  Brackets appearing in BShow.CFG should
  215.     be removed before running and sample data replaced with actual.
  216.  
  217.     Global options which apply to all of BShow:
  218.     -------------------------------------------
  219.  
  220.     / ; *           « if in first column, each designates a comment...
  221.  
  222.     cts=#           « where any non zero value # enables cts/rts hardware
  223.                       flow control.
  224.                       (w/o FOSSIL)
  225.  
  226.     del_dir=#       « where # is the del directory mode.  If it's zero,
  227.                       it leaves the work directory in place, otherwise,
  228.                       it deletes it.  Note that if a work directory
  229.                       is specified with full path, it may be left in
  230.                       place without worrying about having multiple
  231.                       directories created.
  232.                       0=OFF=DEFAULT=LEAVE.  NOT-ZERO=ON=DELETE.
  233.  
  234.     directvideo=#   « force BIOS (0) or direct (1) screen writes
  235.  
  236.                       Note:  If BShow detects DESQview, it will default
  237.                              to BIOS screen writes, otherwise direct
  238.                              screen writes are the default.
  239.  
  240.     lines=#         « the number of lines per page.  This determines the
  241.                       number of lines between page breaks.
  242.  
  243.     max_blanks=#    « the maximum number of consecutive blank lines to
  244.                       display.  Documents often begin with several pages
  245.                       of blank lines, and this feature cuts down on
  246.                       display time.
  247.  
  248.     max_idle=#      « the maximum idle time in seconds to allow user
  249.  
  250.     max_line=#       « the maximum number of lines per file to display
  251.                        to a user.  Good to prevent users from "viewing"
  252.                        a 300K text file to save a download credit.
  253.  
  254.     max_time=#      « designates the maximum amount of time to allow a
  255.                       user to be in a BShow session.  The LESSER of
  256.                       either the command line OR the config file will
  257.                       be used by BShow.
  258.  
  259.                       example:     max_time=10
  260.  
  261.                                     6
  262.  
  263.  
  264.     swapping=#      « where # is the swapping mode.
  265.                       0=OFF=DEFAULT.  NON-ZERO=ON.
  266.  
  267.                       When BShow shells out to the unpacker/lister, it can
  268.                       either do one of two things:
  269.  
  270.                          1) It can shell to DOS by running a second copy of
  271.                             COMMAND.COM (leaving all of BShow in memory) and
  272.                             then run the unpacker/lister.
  273.  
  274.                          2) It can take the BShow code in memory, and
  275.                             copy it to EMS/XMS/HMA/Disk, freeing up that
  276.                             memory for use by the unpacker/lister.  When
  277.                             the unpack/lister is finished, BShow is
  278.                             reloaded into conventional DOS memory, and
  279.                             execution resumes.
  280.  
  281.                       The default is off because there have been certain
  282.                       compatibility problems between BShow and some
  283.                       ill-behaved programs.  BShow will also function
  284.                       faster with swapping off, so if possible, DON'T SWAP!
  285.  
  286.     work_dir=       « same function as the command line parameter.
  287.  
  288.     xon=#           «  where any non zero value # enables xon/xoff software
  289.                        flow control.
  290.                        (w/o FOSSIL)
  291.  
  292.                                     7
  293.  
  294.               Format options unique to each compression utility
  295.               =================================================
  296.  
  297.     end             « ENDS the series of options started by the previous
  298.                       "format_xxx" command.
  299.  
  300.     first_waitfor=  « the string to watch for, to signal the beginning
  301.                       of the file list.
  302.  
  303.     format_xxx      « BEGINS compression-program-specific-section series of
  304.                       options used only if target file extension is ".xxx" .
  305.  
  306.                 example:   format_zip
  307.                            unpack_com=pkunzip %file% %filespec% > %listfile%"
  308.                            list_com=...
  309.                            end
  310.  
  311.     header1=        « the string to display once per screenful of data,
  312.                       while viewing the files.
  313.  
  314.     header2=        « the string to display once per screenful of data,
  315.                       right after header1.
  316.  
  317.     list_com=       « string containing the path and parameters used to
  318.                       run the lister.  This should give a list of the
  319.                       files in the archive.
  320.  
  321.                       You can put several different variables that are
  322.                       replaced by Bshow with parameters originally
  323.                       passed from the command line.  These include:
  324.  
  325.                       %file%       - the archive name
  326.                       %filespec%   - in unpack mode, this is the file to
  327.                                      unpack, in list mode, it's the
  328.                                      filespec for lists.
  329.                       %listfile%  - the listfile used by Bshow.
  330.  
  331.                       Examples:
  332.  
  333.         list_com=spawn /m:160 /w "lha.exe l %file% %filespec% > %listfile%"
  334.         unpack_com=spawn /m:160 /w "lha.exe e -y %file% %filespec% > nul"
  335.  
  336.                        or
  337.  
  338.         list_com=lha.exe l %file% %filespec% > %listfile%
  339.         unpack_com=lha.exe e %file% %filespec% > nul
  340.  
  341.                       Note the positioning of the quoted strings used
  342.                       when SPAWN is used for DESQview operation.
  343.  
  344.     offset1=        « number of characters to strip off the beginning
  345.                       of the string read from the list of the files in
  346.                       the archive.
  347.  
  348.                                     8
  349.  
  350.     offset2=        « number of characters to strip off the END of the
  351.                       string read from the list of the files in the
  352.                       archive.
  353.  
  354.                       Offset1 and 2 are used to strip certain characters
  355.                       off the string, to make it fit into 80 columns.
  356.  
  357.     offset3=        « which column the filename starts in each line read
  358.                       from the file listing.
  359.  
  360.     second_waitfor= « the string to watch for, to signal the END of
  361.                       the file list.
  362.  
  363.     unpack_com=     « string containing the path and parameters used to
  364.                       run the unpacker.
  365.  
  366.     For examples see the included example files or BSHOW.CFG.
  367.                                     9
  368.  
  369.  
  370.                            Menu Options in BShow
  371.                            =====================
  372.  
  373.     From the Main prompt:
  374.  
  375.      [Main] <L,#,?=Help,[Enter]=Exit>: ?
  376.  
  377.       'L'        - relists the directory with the SAME filespec.
  378.       #          - the number corresponding to the file you wish to view.
  379.       [name]     - the name of the file you wish to view.
  380.       [wildcard] - relists the directory with a NEW filepsec.
  381.       [enter]    - exits BShow.
  382.  
  383.  
  384.     From within the directory listing:
  385.  
  386.      [Dir] <A,C,L,M,N,Q,#,?=Help>:
  387.  
  388.       'M' or
  389.       [enter]    - Continues file listing with next page.
  390.       'N'        - Quits listing files, and goes directly to main prompt.
  391.       'L'        - Relists the directory from the beginning.
  392.       'C'        - Enters continuous text viewing mode, without these prompts
  393.                    Note that you may press any key to abort continuous mode.
  394.       #          - The number corresponding to the file you wish to view.
  395.       [name]     - The name of the file you wish to view.
  396.       [wildcard] - Relists the directory with new filespecs.
  397.       'Q' or 'A' - Exits BShow RIGHT NOW!!
  398.  
  399.     From within a Text or Binary listing:
  400.  
  401.      [List - 32% done] - <A,B,C,M,N,S,Q,?=Help>: ?
  402.  
  403.      'M' or
  404.      [Enter]     - Lists next page of file.
  405.      'C'         - Enters continuous viewing mode.  This will eliminate all
  406.                    prompts.  Note that you can enter normal mode again by
  407.                    pressing any key.
  408.      'B'         - Backup one page, and list it (view previous page).
  409.      'S'         - Starts a string search in either text or binary modes.
  410.      'N'         - Returns to directory list mode.
  411.      'Q' or 'A'  - exits BShow RIGHT NOW!!
  412.                                     10
  413.  
  414.                    Adding Compression Utility Interfaces
  415.                    =====================================
  416.  
  417.     BShow has been designed so that as compression programs are created
  418.     or improved, they may be utilized by the sysop.
  419.  
  420.     This is a sample archive listing, generated by LHA 2.13 using the
  421.     "lha l test.lzh" command.  This is the straight listing, no comments.
  422.  
  423.     -=-=-=-=- LISTING STARTS BELOW THIS LINE -=-=-=-=-
  424.  
  425.     Listing of archive :  TEST.LZH
  426.  
  427.       Name          Original    Packed  Ratio   Date     Time   Attr Type  CRC
  428.     --------------  --------  -------- ------ -------- -------- ---- ----- ----
  429.       SOURCE.C          2779      1203  43.3% 91-09-29 14:47:42 a--w -lh5- 1D2E
  430.       SOURCE.OBJ        8066      2438  30.2% 91-09-29 03:07:40 a--w -lh5- 4B91
  431.       SOURCE.EXE        1368       447  32.7% 91-09-24 21:02:48 a--w -lh5- 659C
  432.       OTHER.FIL         4478      1285  28.7% 91-09-29 14:46:16 a--w -lh5- 0A02
  433.       MORE.FIL          5275      1460  27.7% 91-09-29 14:44:32 a--w -lh5- 18B5
  434.       JUNK.EXE          3312      1039  31.4% 91-09-05 09:47:44 a--w -lh5- 0378
  435.       MISC.COM          2152       812  37.7% 91-09-29 14:42:06 a--w -lh5- EE1A
  436.       HELPME.DOC        5780      3516  60.8% 91-09-29 14:47:48 a--w -lh5- C5DE
  437.       READ.ALL         12348      7358  59.6% 91-09-29 03:27:32 a--w -lh5- 323E
  438.       HANGON.TOM        2216      1417  63.9% 91-09-29 03:27:34 a--w -lh5- 5CB9
  439.       FORGET.ME         7139      4271  59.8% 91-09-29 14:47:26 a--w -lh5- D415
  440.       MORE.C            6414      3797  59.2% 91-09-29 14:44:40 a--w -lh5- 08C0
  441.       TEST.FIL          3219      2188  68.0% 91-09-29 14:42:36 a--w -lh5- 777F
  442.     --------------  --------  -------- ------ -------- --------
  443.         13 files       64546     31231  48.4% 91-09-29 15:25:20
  444.  
  445.     -=-=-=-=- LISTING ENDS ABOVE THIS LINE -=-=-=-=-
  446.  
  447.  
  448.     What follows is the same text file - with comments. They describe
  449.     what each parameter in the configuration does to process this file
  450.     listing, as well as all others generated by LHA.  Follow this procedure
  451.     with any similar compression program, and BShow should work with it.
  452.     "//" designates a comment line, and starts in what represents the first
  453.     column of the listing.
  454.                                     11
  455.  
  456.     -=-=-=-=- LISTING BEGINS BELOW THIS LINE -=-=-=-=-
  457.  
  458.     Listing of archive :  TEST.LZH
  459.  
  460.     //This next line is the format1= line.  First line of every page.
  461.       Name          Original    Packed  Ratio   Date     Time   Attr Type  CRC
  462.     //
  463.     // This next one is the format2= line, AS WELL AS, the waitfor1= line.
  464.     // BShow reads until it encounters this string, and then everything from
  465.     // then on are file listings.
  466.     //
  467.     --------------  --------  -------- ------ -------- -------- ---- ----- ----
  468.     // notice that the offset1=2 means which column the file names start in.
  469.     // In LHA, they start in column 2.
  470.       SOURCE.C          2779      1203  43.3% 91-09-29 14:47:42 a--w -lh5- 1D2E
  471.       SOURCE.OBJ        8066      2438  30.2% 91-09-29 03:07:40 a--w -lh5- 4B91
  472.       SOURCE.EXE        1368       447  32.7% 91-09-24 21:02:48 a--w -lh5- 659C
  473.       OTHER.FIL         4478      1285  28.7% 91-09-29 14:46:16 a--w -lh5- 0A02
  474.       MORE.FIL          5275      1460  27.7% 91-09-29 14:44:32 a--w -lh5- 18B5
  475.       JUNK.EXE          3312      1039  31.4% 91-09-05 09:47:44 a--w -lh5- 0378
  476.     //
  477.     // Two other parameters, the offset1, and offset2, delete spaces, or
  478.     // characters from the end of strings.  This is to clarify things.
  479.     // Offset2=1 will delete 1 character off the beginning of the line,
  480.     // just before displaying it. offset3=1 will chop one character off
  481.     // the end of the string.  If lines take up two lines, because they
  482.     // are too long, you can use these options to trim them down.
  483.     //
  484.       MISC.COM          2152       812  37.7% 91-09-29 14:42:06 a--w -lh5- EE1A
  485.       HELPME.DOC        5780      3516  60.8% 91-09-29 14:47:48 a--w -lh5- C5DE
  486.       READ.ALL         12348      7358  59.6% 91-09-29 03:27:32 a--w -lh5- 323E
  487.       HANGON.TOM        2216      1417  63.9% 91-09-29 03:27:34 a--w -lh5- 5CB9
  488.       FORGET.ME         7139      4271  59.8% 91-09-29 14:47:26 a--w -lh5- D415
  489.       MORE.C            6414      3797  59.2% 91-09-29 14:44:40 a--w -lh5- 08C0
  490.       TEST.FIL          3219      2188  68.0% 91-09-29 14:42:36 a--w -lh5- 777F
  491.     //
  492.     // This is the waitfor2= line.  If it doesn't find this string anywhere,
  493.     // it keeps reading, line by line, until it encounters EOF.
  494.     //
  495.     --------------  --------  -------- ------ -------- --------
  496.         13 files       64546     31231  48.4% 91-09-29 15:25:20
  497.  
  498.     -=-=-=-=- FILE LISTING ENDS ABOVE -=-=-=-=-
  499.  
  500.                                     12
  501.  
  502.                        Credits, Copyrights, and Thanks
  503.                        ===============================
  504.  
  505.     This documentation has been prepared by Jim Wargula, Sysop of JW-PC
  506.     DataFlex.HST RBBS, where Alpha and Beta testing of BShow, modem
  507.     distribution, and modem support are based.  Please feel free to comment
  508.     on any documentation errors or omissions.  The docs are slowly being
  509.     improved and ways of expanding them for more clear explanations will
  510.     be explored...
  511.  
  512.     This documentation has been edited by Tim Sandee and Ben Sandee.
  513.  
  514.     BShow is Copyright (c) Ben Sandee, 1991 and may not be distributed
  515.     as part of any other package or by any commercial enterprise without
  516.     the express knowledge and consent of the author.  BBS systems are
  517.     given permission to distribute BShow in the Shareware version.
  518.  
  519.     Utility programs called by BShow are copyrighted by their respective
  520.     authors and should be registered as required.
  521.  
  522.     Thanks to:
  523.  
  524.           Jim Wargula - alpha tester, beta tester, support,
  525.                         documentation.
  526.  
  527.           John Fox      \
  528.           Ken Geen       \
  529.           Roy Jacobs   ---- Beta testers, ideas, support.
  530.           Ron Mainguth   /
  531.           Mark Simmons  /
  532.  
  533.           Tim Sandee -  documentation, ideas.
  534.  
  535.           All the SysOps out there who make BBS'ing more enjoyable.
  536.           This is dedicated to you guys.
  537.  
  538.     Document revision 1.01, 05-18-92
  539.